<?php
namespace ChatX\Storage;

interface Driver
{
    /**
     * 连接存储服务
     * @param array $config 配置参数
     * @return bool 连接是否成功
     */
    public function connect(array $config): bool;

    /**
     * 上传文件
     * @param string $bucket 存储桶名称
     * @param string $objectKey 对象键名
     * @param string $filePath 本地文件路径
     * @param array $options 额外选项
     * @return array|false 上传结果或失败返回false
     */
    public function upload(string $bucket, string $objectKey, string $filePath, array $options = []);

    /**
     * 下载文件
     * @param string $bucket 存储桶名称
     * @param string $objectKey 对象键名
     * @param string $savePath 保存路径
     * @param array $options 额外选项
     * @return bool 下载是否成功
     */
    public function download(string $bucket, string $objectKey, string $savePath, array $options = []);

    /**
     * 删除文件
     * @param string $bucket 存储桶名称
     * @param string $objectKey 对象键名
     * @return bool 删除是否成功
     */
    public function delete(string $bucket, string $objectKey): bool;

    /**
     * 获取文件信息
     * @param string $bucket 存储桶名称
     * @param string $objectKey 对象键名
     * @return array|false 文件信息或失败返回false
     */
    public function getInfo(string $bucket, string $objectKey);

    /**
     * 生成文件访问URL
     *
     * @param string $bucket 存储桶名称
     * @param string $objectKey 对象键名
     * @param int $expires 过期时间(秒)
     * @return string|false 访问URL或失败返回false
     */
    public function getUrl(string $bucket, string $objectKey, int $expires = 3600);

    /**
     * 列出存储桶中的对象
     *
     * @param string $bucket 存储桶名称
     * @param array $options 额外选项
     * @return array|false 对象列表或失败返回false
     */
    public function listObjects(string $bucket, array $options = []);
}